Graphics Bonanza/Graphics Bonanza.iso/prog2/wgt35/wspr.doc

Text File | 1993-01-28 | 9.1 KB | 303 lines

            WSPR.LIB Documentation
            ~~~~~~~~~~~~~~~~~~~~~~

    The WordUp Graphics Toolkit Version 3.5 includes a special
library for sprites.  The library allows you to edit sprites using
the WGT Sprite Creator, load them in your program, and display
them on the screen.  The best part about the sprites is you can
set up movement and animation sequences and the library will handle
everything for you.


Using WSPR.LIB
~~~~~~~~~~~~~~
    To use the library, you must also link wgt.lib, and include
wgt.h and wspr.h.  The library needs a lot of memory so make sure
you have lots, and set the program heap size in the Options\Debugger
menu.




            Sprite Procedures
            ~~~~~~~~~~~~~~~~~

wloadpsprites and wfreesprites have been moved to the main library.

void initspr(void);

    Initializes sprite library.
    Sets up internal variables, and makes a virtual screen
    called 'spritescreen'.

    Assumes you have loaded sprites into an array called 'sprites'.
    You must call it sprites for these routines to work.

    You must call this after you load in sprites using wloadsprites.
    If you need to call this more than once in a program, you
    must free the virtual screen by wfreeblock(spritescreen).

    Example usage:
        initspr();


--------------------------------------------------------------------------


void spriteon(int spritenum,int x coord,int y coord,int arrnumber);

    Turns a sprite on at the coordinates, using the arrnumber block
from the sprites array.  Arrnumber is the same as the sprite numbers in
the WGT Sprite Creator.  Spritenum can range from 1 to 40.  This means you
can have 40 sprites on the screen at once.
    Each call to spriteon must be followed later in the program by
a spriteoff.  Do not call spriteon using the same spritenum twice in a row
or the computer may hang. You must turn the sprite off and back on again.

    Example usage:
        spriteon(1,160,100,3);


--------------------------------------------------------------------------


void spriteoff(int spritenum);

    Turns off a sprite. See above.

    Example usage:
        spriteoff(3);


--------------------------------------------------------------------------


void animate(int spritenum,char *animation sequence);

    Sets up animation for a sprite.  Spritenum is the sprite number
to animate.  The string you must pass takes the following form:

    "(arrnumber,delay)(arrnumber2,delay2)R"

Between each set of brackets is the information required to animate the
sprite.  The first number is the sprite array number, and the second is
how long that sprite number is displayed. You then make another set and use
different sprite numbers and delays.  If you place a CAPITAL R at the end
of the string, the animation will (R)epeat itself when it gets to the end.
If you leave the R out, the animation will occur once, and stop.
You can have 40 sets for animation.

For example: To animate sprite number one between two sprites, and repeat:

    Animate(1,"(1,0)(2,0)R");
        ^   ^    ^   ^
        |   |    |   | R repeats the sequence
        |   |    |
        |   |    |Second sprite shown is number 2, with no delay
        |   |
Sprite to animate   |First sprite shown is number 1, with no delay

After calling this procedure, you must turn the animation on with animon.

    Example usage:
        Animate(4,"(5,12)(69,0)(200,100)");


--------------------------------------------------------------------------


void animon(int spritenum);

    Turns animation on for the sprite.  See above for setting animation.

    Example usage:
        animon(3);


--------------------------------------------------------------------------


void animoff(int spritenum);

    Freezes animation for the sprite.

    Example usage:
        animoff(3);


--------------------------------------------------------------------------


void movex(int spritenum,char *movement sequence);

    Sets up horizontal movement for a sprite.
    Works the similar to animate only there are 3 numbers in each set.
    You can have 15 sets for movement.

    movex(3,"(1,50,1)(-1,50,0)R");

    The first number in the set is added to the current x coordinate
of the sprite.  Therefore if the sprite is at 100,50 on the screen, and
you make the number a 5, the sprite will move to 105,50.  This number can
be anything, so you can have the sprite move right (positive numbers),
left (negative numbers) or nowhere (zero).

    The second number in the set is the number of times to move the
sprite before going on to the next set.  Always >0!

    The third number in the set is the delay for each time the sprite
moves. Try using 0 at first and increase it to slow the sprites down.

    If the set was (1,50,1), then the sprite would move to the right
one pixel, 50 times, with a delay of 1 for each move.  Then the next set
would be activated. If you have a CAPITAL R at the end of the string,
the movement will repeat.

    For example, to make sprite 2 move back and forth on the screen
continuously:
    movex(2,"(1,200,0)(-1,200,0)R");

    To make a sprite move from the left side to the right, and jump
back to the left again:

    movex(2,"(1,319,0)(-319,1,0)R");
               ^
               | This moves the sprite 319 pixels to the left!


--------------------------------------------------------------------------


void movey(int spritenum,char *movement sequence);

    Sets up vertical movement for a sprite.
    Exactly the same a movex. See above.


--------------------------------------------------------------------------


void movexon(int spritenum);

    Turns horizontal movement for a sprite on.

    Example usage:
        movexon(3);


--------------------------------------------------------------------------


void movexoff(int spritenum);

    Turns horizontal movement for a sprite off.

    Example usage:
        movexoff(3);


--------------------------------------------------------------------------


void moveyon(int spritenum);

    Turns vertical movement for a sprite on.

    Example usage:
        moveyon(3);


--------------------------------------------------------------------------


void moveyoff(int spritenum);

    Turns vertical movement for a sprite off.

    Example usage:
        moveyoff(3);


--------------------------------------------------------------------------


int overlap(int spritenum 1,int spritenum 2);

    Tests if two sprites overlap each other on the screen.
    Returns 1 if they are overlapping.
    (Used for detecting collisions)

--------------------------------------------------------------------------



**************************************************************************


The sprite library uses the following variables:

int spon=15;        - the highest sprite number used in your program
int spclip=1;        - 0 means sprite clipping is off
             (might hang computer is it is off)
block spritescreen;        - the virtual screen used as a background


A large structure contains all data about the sprites:

typedef struct {
      int num;           // sprite number to show on screen
      int x;                   // x coord
      int y;                   // y coord
      int ox;                   // last x coord
      int oy;                   // last y coord
      unsigned char on;               // sprite is on?
      int maxx;                   // area on screen to copy
      int maxy;                   // Upper left and
      int minx;                        // Bottom right corners of box
      int miny;                        // to copy.
      block old;                       // old block (stores what was
                              behind sprite)

      char animon;               // animation on?
      int anm[41];                     // number of animation
      unsigned char ans[41];           // delay for animations
      char curan;               // current animation
      unsigned char delcnt;           // delay count

      char movexon;               // x movement on?
      int mvx[16];               // direction to move
      int mvn[16];               // number of times to move
      unsigned char mvxs[16];           // delay for movement
      char curxmove;               // current x move
      int curmnx;               // number of times moved already
      unsigned char mvxcnt;           // delay count

      char moveyon;               // y movement on?
      int mvy[16];               // direction to move
      int mvny[16];               // number of times to move
      unsigned char mvys[16];           // delay for movement
      char curymove;               // current y move
      int curmny;               // number of times moved already
      unsigned char mvycnt;            // delay count

      } sprit;
sprit s[40];

You will probably not need to change any of these.  There are a few
applications however.

If you need to store the movements or animations as integers, it will be
a pain converting the numbers into a correct string to pass to the animate
command, therefore you can just put them directly into the arrays yourself.

If you draw something other than a sprite on the virtual screen, you will
need to copy more of the screen to the visual page.  Therefore change the
minx,miny,maxx,maxy variables of a sprite that is on to the coordinates
of the area you need to copy.  See breakout.c for an example of this.